Micrometre conversions are always positive and finite; check and design exit 1 on errors (#93) - #133

Fixes #93

Also fixes the CLI exit-status mismatch found in the review of #130, and three gaps found while implementing (fixed in review).

Summary (by module)

• length_units (new, pure): the unit table, space_unit, to_micrometers, SPACE_UNITS and UnsupportedUnitError, moved out of physical_sizes, which re-exports them (MorphoFeature calibration.py and MorphoRelate io/headers.py import them from physical_sizes; checked). to_micrometers always returns a positive finite number: an overflow (1e308 m gives inf), an underflow (1e-320 pm gives 0.0) or an int beyond the float range (10**400) raises a ValueError naming the value and unit.
• physical_sizes:
  • PhysicalSizes.micrometers converts with to_micrometers and returns None for such a size, never inf; same_pixel_size returns None and pixel_size_groups leaves the size out (both raised before). _same_length is False when either size is not finite.
  • A header size (TIFF OME/ImageJ, OME-Zarr) that does not convert is None, with the axis and value in PhysicalSizes.invalid; so is an OME-Zarr level-0 scale times the image's scale that overflows or underflows.
  • (review) A TIFF OME (PhysicalSizeX/Y/Z, TimeIncrement) or ImageJ (spacing, finterval, a resolution tag of 0 with a unit) size that is itself inf, NaN, zero, negative or not a number is also recorded in invalid (before, silently None): the TIFF counterpart of [Sad Catapella B6][Scientific QA] Malformed explicit NGFF coordinate transforms are silently treated as unknown calibration #94.
• pixel_size_checks: invalid_physical_calibration names these images with the value; (review) its message agrees with the count ("1 image gives a calibration in its metadata ... this image is", before "1 image give ... their ... these images are").
• calibration: a stated size that does not convert is refused, so calibration.csv and calibrate name the line or option.
• cli: check exits with 1 on an experiment design it cannot read; (review) and on a design with repeat_group_conflict or invalid_experiment_design, now printed as an error after the design summary (before, described in the summary with exit 0, while run stops on it). The filter is shared with design as cli_design.design_errors.
• cli_design: design exits with 1 when the design it prints has repeat_group_conflict or invalid_experiment_design, also after writing a change.
• run, masks, calibrate and convert already return 1 on every error they print.
• Docs: contract §2, §9.2 (Exit status row), §9.3, §11, §16; user guide §5 (Exit status) and §8; plan question 66 and the §10 entry; AGENTS map.

Decisions (plan §12 question 66; decided, pending the owner's confirmation)

Coordinator's answers in review, recorded in the plan for the owner to confirm:

1. A header size that overflows or cannot be converted is a warning (invalid_physical_calibration; the image uncalibrated with the reason), consistent with the owner's [Sad Catapella B6][Scientific QA] Malformed explicit NGFF coordinate transforms are silently treated as unknown calibration #94 decision. A stated size that does not fit is refused.
2. Every command exits 1 when it prints an error, 0 otherwise; argparse exits 2. design exiting 1 after a write that leaves a conflict is accepted.

Question number 66 follows the highest on main (64 and 65 from #128).

Tests

• tests/test_micrometre_conversion.py (36 tests) and tests/test_cli_exit_status.py (4 tests). The review's 13 new tests fail on the PR head before the review fixes (12 conversion/message, 1 exit status).
• Full gate (review worktree, Linux, Python 3.13, .[dev,notebook,zarr], root): ruff check and format clean (190 files), tools/check.py --rules clean, pytest 1941 passed, 2 skipped (expected: test_discovery.py:665 root permissions, test_cli_log.py:164 case-sensitive file system), 1 warning.

§9 figures (measured at 88f3202)

• Largest file touched: physical_sizes.py 597 lines (684 on main; baseline entry removed). length_units.py 161, cli.py 341, pixel_size_checks.py 312, calibration.py 464, cli_design.py 156.
• Largest function touched: cli._check and ngff_physical_sizes, 45 executable lines; most statements _check 39.
• Highest complexity touched: cli._check 9; to_micrometers, ngff_physical_sizes 7.
• Most parameters touched: _sizes 7.
• Baseline: 3 entries removed against main (physical_sizes.py file length; _ome_sizes, _imagej_sizes now have docstrings); none added. # noqa count unchanged (54).
• Layers: length_units declared pure (no I/O).

Known, not in this PR

• to_micrometers refuses NumPy scalars other than float64 (np.float32, np.int64: "not a number"), as on main.

https://claude.ai/code/session_01G3qp9AxjpGPw9xfWAUJNqc

🤖 Generated with Claude Code